Data Sources

App Studio allows you to use data in your mobile apps from the following sources:

  • ADO Databases.

  • Restful Web APIs via NDL's Connect gateway.

  • SOAP and RESTful Web Services.

  • NDL awi Web Services.

  • Microsoft Outlook Contacts and Appointments.

At runtime, your app can send a request to any of these sources and ask it to send data to the app. We call this downloading data and if you display the data within your app, we say the data is input mapped to the Controls which display the data. You don't have to display downloaded data which users don't need to see.

Within your app, you can display and allow users to edit downloaded data and/or to enter new data and you can manipulate the data within your app using the Digitise Apps Scripting language. Data within the app can be sent from the mobile device to the same remote sources listed above. When data is sent from the mobile device we call it uploading the data and if the data is taken from Controls on a form, we say the Controls are output mapped to the data source.

Data can be passed in either or both directions – i.e. you can both download and upload data within the same app or just upload or just download as needed. You can upload to and download from multiple sources in a single app and you can upload to and download from the same or different sources depending upon the requirements of the app you are creating.

Within your app you need to be able to store data downloaded from a remote source, new data entered by a user and data edited by a user. To store this data, your app will create one or more local databases on each device and add a table to the database for each remote source you specify when you create the app. Within your Project, we call these local tables Data Sources. You can add as many Data Sources to an app as you need within App Studio and you can add more than one Data Source for the same remote source if you want or need to.

When you add a new Data Source to your app, you are effectively specifying the data columns which will define the structure of a local table to hold data associated with a remote source. The columns you specify should match the data you expect to receive from and/or send to the corresponding remote source. This is simplified by allowing you to display the structure of a remote source and then choose those data items within that source that you want to allow for in your app. App Studio will automatically create a database table which includes a column for each data item you select. Data items which you don't need can be ignored. For example, the remote source might include names and addresses but within your app you might only be interested in names and postcodes, meaning you can ignore such things as house number, street name and town.

Where you will be uploading and downloading data to the same remote source, you can use the same Data Source for both. In some cases, however, it might be simpler or more efficient to create separate Data Sources for uploading and downloading, e.g., where the data transferred will be different in each direction.

Data Sources which are linked to the remote sources listed above, can only hold data from and/or for one remote source. If you want to combine data from more than one remote source in a single table on the device, you will need to define your own table and specify its data columns manually. These Data Source tables are called Custom Tables. You can also use Custom Tables to allow for data which isn't linked to a remote source, or to specify SQL queries which aren't allowed for with the standard data sources.

At runtime, when data is downloaded or entered by a user, it will be stored as records in the Data Source's local table, with each record being one row within the table.

  • Within this online help, we will refer to remote sources as remote data sources and references to Data Sources signifies local Data Sources.

 

As we have seen, therefore, you can define a Data Source by reference to a physical remote data source or you can define your own Custom Table.

For example, suppose you want to download data to your device from a remote database. In this case, you can point App Studio at the database which will display the tables and data items available in that database. From this display, you can then select those data items in the remote database which you want to be able to download. App Studio will define local tables to contain the sub-set of tables, and their data items, that you select. You can include all the required tables and data items from a single remote data source in one Digitise Apps Data Source. Alternatively, depending upon the requirements of your app, it may make more sense to split the relevant data items across multiple Data Sources. You can include tables and data items in more than one Data Source if you need to.

Likewise, with Web API and web service data sources, App Studio will display the data items which can be passed to the Web API or web service and those which will be returned from it, allowing you to define local tables based on the Web API/web service data you want to work with.

ADO Database, Web API and Web Service Data Sources map all or part of a remote Target data source to a Data Source within your Digitise app and each Digitise Apps Data Source can only contain data items from a single remote data source. These Data Sources can be used within your app to download data to the device and upload it to the target data source.

If you want to combine data from multiple remote data sources, you can use Custom Views or Custom Tables.

Custom Views effectively provide a 'window' onto the data held in the local databases on the device. A SQL Select statement is used to select which records from which local tables you want to include within an individual View and you can configure different Views to provide different data sets. Views are mainly used to display data and can be especially useful where you want to combine data from different tables, for example in a ListView. A View is like a virtual table containing the records defined by a SQL statement. You can display the contents of data items in the records and move through the record set but you cannot add new records, update records or download or upload data using a View. To do these things you need to use Custom Tables or the Data Sources themselves.

With Custom Tables, you can define your own tables containing only the data items you want to hold in them. You can use Custom Tables to hold data which is generated locally on the device and isn't downloaded from a remote data source, or you can use them to temporarily hold data from other Data Sources to allow you to display, manipulate and edit the data more easily. You can also create Custom Tables by copying existing Data Source structures. Data is normally input to a Custom Table by copying it from other Data Sources, although you can download data directly to a Custom Table from a remote ADO database data source but not from other types of remote data sources, such as web services. Examples of when you might use Custom Tables include storing data which is locally generated only, separating reference data from editable data so that the reference data isn't accidentally overwritten or combining data from different remote data sources into a single table so that you can manipulate the combined data set or display the combined data in a single list. You can add and modify records in a Custom Table but you cannot update remote Target data sources from a Custom Table. To do this you need to copy the relevant data from the Custom Table to another type of Data Source and upload the data from there. You can mix data from different Data Sources within a single Custom Table.

 

Remember, within your local tables, you only need to include those data items that you want to use within the Project; you don't have to tell App Studio about those items which aren't relevant to your app. For example, as in our earlier example where your remote data source lists people's names and addresses but your app will only require their names and post codes, and hence you only need to include the name and post code fields within your Data Source; you can ignore the other lines of the address.

  • When defining a Data Source during the development of a Digitise Apps Solution, you will need to specify a connection string in order to connect to and develop with a specific Data Source. Within your Solution, however, you can change the connection string programmatically, for example allowing you to simplify moving between test and live data, and you can also change Data Source connection strings for published apps within the App Manager utility, preventing the need to edit a Solution after it has been published solely for the purpose of changing the connection string.

 

Once you have defined a Data Source, you can map the data items contained in it to Controls on your forms and/or access and manipulate them in your Scripts. Mapping data items to Controls allows you to display data downloaded to the device and can be used to allow users to modify downloaded records or create new records. Scripts are used to initiate uploads and downloads and can also be used to manipulate data behind the scenes.

In most Digitise apps, data is downloaded to a device from one or more remote data sources and is stored in your Digitise Apps' Data Source Tables from where it can be viewed, edited and added to by the user. Data on the device can be viewed, edited and created via the Controls you place on the forms making up the app and/or within the Scripts you write to provide the app's functionality. Since your data is stored in local database tables, your app works with the data as standard database records.

Scripting Methods are provided to download data from remote data sources to the device and to upload data back to the back-office. Apart from these Methods, other Scripting Methods are provided allowing you to work with the data on the device. These other Methods only affect records in the local database tables, they do not directly interact with the remote data sources. Creating a new record in a local database may later translate into a new record being added to the remote data source, or it may update an existing record on the remote data source which wasn't included in the original download. Deleting a record only deletes the record from the local database, it doesn't specify that the equivalent record should be deleted from the remote data source.

Modified data is then usually uploaded from your app to the back office where it can be used to update remote data sources. If the data is uploaded to a remote ADO database data source, the uploaded data can be used to update existing records or insert new records, and each data record must include the relevant Primary Key(s) for the database being updated. Foreign Keys can be resolved and updated at the same time. If the remote data source is a web service or Web API, what happens to the data passed to the web service or Web API is determined by the functionality programmed into the web service or Web API and is not under Digitise Apps' control.

 

Data can be downloaded and uploaded on an ad hoc basis as required and signal strength or availability permits or you can download or upload your data in one go, e.g. at the start or end of the day.

Data transfers can be synchronous or asynchronous:

Synchronous data transfers will pause your app while the transfer is performed, preventing the user from doing anything within the app until the transfer completes. Whilst a synchronous transfer is in progress by default the Digitise Apps Client will display a progress bar and the user can cancel the transfer using the cancel button displayed. You can display a busy indicator in place of the progress bar and prevent users cancelling the transfer using the SetApplicationOption Scripting Method.

Some additional useful information about what happens if a synchronous transfer is interrupted can be found under the Notes: in the description of the IsRetrySyncAvailable Scripting Method.

Asynchronous transfers, on the other hand, occur in the background allowing users to continue working in the app whilst the transfer is performed. No progress bar is displayed and you will need to inform users when the transfer completes within your app. Local tables included in a data transfer transaction can be read by the app whilst the transfer is in progress but are locked to data updates until the transfer finishes, or is cancelled, to prevent the potential for inconsistencies between the local and remote data. You can only have one asynchronous transfer in progress at any one time and you must wait for it to complete before you can set off another transfer, either synchronous or asynchronous. If a transfer is interrupted, for example because the signal disappears, the Digitise Apps Client will automatically retry at (increasing) intervals until the transfer is successful or you cancel the transfer within a Script or the App Server reports an error such as access denied or invalid permissions. Closing the Digitise Apps Client or Standalone App will automatically cancel any asynchronous transfer which is in progress.

 

You can add Data Sources at any time during the creation and editing of your Project, but obviously, you won't be able to map the data items to a Control or access them within a Script until you have defined them within the Project.

You may also need to modify a Data Source after an app has gone live, e.g. as a result of changes in a new version of a back-office system or because of changes in the way users need to work with their mobile devices. When developing the new version of your app you will need to consider the possibility that, after the users upgrade, there may still be data held on their mobile devices, entered using the previous version, which hasn't yet been synchronised with the back office. You should create new Data Sources to provide and process the new data set(s) required and leave the original Data Sources untouched which can then be used to synchronise the existing data, if there is any.

If you only need to change the connection details for a remote data source, for example, because the data source has been moved to a new server, you can do this within App Manager without having to edit and redistribute your app(s).

 

For information on how to define your Data Sources and specify the data items within them that you want to use, see the following topics:

Add an ADO Databases

Add a Web API Data Source

Add a RESTful Web Service Data Source

Add a SOAP Web Service Data Source

Custom Tables

Custom Views

Add PIM Data Sources

Add an awi Web Service Data Source